Troubleshooting macOS Sensor

Cyberhaven can troubleshoot many issues successfully without requiring additional logs from devices. However, in the event Cyberhaven needs to collect additional information in order to troubleshoot a sensor issue such as a device that cannot communicate with the backend, it may be necessary to generate a diagnostic package that can be shared with and triaged by Cyberhaven support.

Status, Stopping, Starting, or Uninstalling

To check the macOS Cyberhaven sensor status, run the following command in the Terminal application.

sudo /Applications/Cyberhaven.app/Contents/Resources/status.sh

To stop the macOS Cyberhaven sensor, run the following command.

sudo /Applications/Cyberhaven.app/Contents/Resources/stop-all.sh

To start the macOS Cyberhaven sensor, run the following command.

sudo /Applications/Cyberhaven.app/Contents/Resources/start-all.sh

To restart the macOS sensor of Cyberhaven, run the following command.

sudo /Applications/Cyberhaven.app/Contents/Resources/restart.zsh

To uninstall the macOS sensor of Cyberhaven, run the following command.

sudo /Applications/Cyberhaven.app/Contents/Resources/uninstall.sh

Diagnostics

To generate a diagnostic package, run the following command:

sudo /Applications/Cyberhaven.app/Contents/Resources/diagnose.zsh --system

You can omit the --system option to make the script faster, but it is recommended that you keep it.

If this script is not present on the target machine, you can download it from here and invoke it with sudo zsh ./diagnose.zsh --system

Building the diagnosis bundle will take a few minutes, and the result will typically be a few hundred megabytes in size. It will be saved in the same folder as the script you ran—for example:

/Applications/Cyberhaven.app/Contents/Resources/cyberhaven-diagnosis-2021-01-20T1329-64C81D03-C61E-4426-9780-B3352FCF5A25.tgz

Please provide this file to Cyberhaven when requested. You can upload the bundle to Cyberhaven through this web-based form, which is accessible by logging into the Cyberhaven Console. You can safely remove the .tgz file after uploading.

The diagnosis bundle is self-explanatory in what it records (it prints what information is collected at each step). The diagnosis bundle does not collect additional sensitive information on top of what is sent to the Cyberhaven dashboard during normal sensor operation. The bulk of the information consists of:

1. Cyberhaven application logs.
2. System diagnosis profile (this is obtained using Apple's sysdiagnose utility and contains system logs and generic machine information, a spindump of the system, several seconds of fs_usage ouput, several seconds of top output, resident memory usage of user processes, a System Profiler report, recent crash reports, disk usage information and network status).
3. MDM profiles and settings.
4. Apple tccd logs.
5. List of installed applications.

Performance tracing

To generate a performance trace, please run the following command and then reproduce the performance problem:

sudo bash /Applications/Cyberhaven.app/Contents/Resources/trace.sh

The script is self-documented. In order to keep the traced execution short and the corresponding trace size low, by default the script will stop recording after 30 seconds. Since version 21.12 of the Cyberhaven sensor, you can specify a longer tracing duration, for instance this is how you can record a trace of 120 seconds:

sudo bash /Applications/Cyberhaven.app/Contents/Resources/trace.sh -t 120

Use Control-C to stop the trace earlier if needed. An archive will be created in /tmp and Finder will open automatically at the location of the trace.

If you do not have the trace.sh script bundled with the sensor, please download the latest version.

Please provide the archived trace file to Cyberhaven when requested. You can upload the bundle to Cyberhaven through this web-based form, which is accessible by logging into the Cyberhaven Console. You can safely remove the .tgz file after uploading.

The performance tracing script is self-explanatory in terms of what it collects - it is a kernel profile, mostly consisting in kernel and application stack traces. There should not be sensitive information in the profiling trace.

Log Files

Cyberhaven log files are written to the following location. These will be automatically included when generating a diagnostic bundle.

/var/log/io.cyberhaven.lightbeam

Application Files

The live config file included in the diagnostic bundle can be located at,

/Library/Application\ Support/io.cyberhaven.lightbeam/config.json

Validating Full Disk Access

On macOS, to make sure that the Cyberhaven agent has the Full Disk Access permissions required to operate whether you deployed it through

1.  a privacy profile for deployment using MDM or

2.  manually granting permissions for manual installation tests,

you can run the following command in Terminal:

Big Sur or later:

sudo sqlite3 /Library/Application\ Support/com.apple.TCC/TCC.db "SELECT client,auth_value FROM access WHERE service=='kTCCServiceSystemPolicyAllFiles'" | grep '2'$

Catalina:

sudo sqlite3 /Library/Application\ Support/com.apple.TCC/TCC.db "SELECT client,allowed FROM access WHERE service == 'kTCCServiceSystemPolicyAllFiles'" | grep '1'$

The displayed output should contain io.cyberhaven.lightbeam.

Sensor Error

• Non-functional Sensor: If the MDM profile is not installed, the sensor status will be ‘Non-functional Sensor.’ Deploying the MDM profile is required to resolve this issue.